Array Macros

Macros to manipulate one-dimensional dynamic arrays.

Include file: AfxNova/AfxArrays.inc.

Name	Description
AppendElementToArray	Appends a new element to the array.
AppendArrayToArray	Appends one array to another array.
InsertElementIntoArray	Inserts a new element into an array.
InsertArrayIntoArray	Inserts an array into another array.
RemoveElementFromArray	Removes the specified element from an array.
RemoveFirstElementFromArray	Removes the first element from an array.
RemoveLastElementFromArray	Removes the last element from an array.
RemoveElementsFromArray	Removes the specified elements from an array.

Sorting Macros

Include file: AfxSort2.inc.

Name	Description
AfxSortNumericArray	Sorts one-dimensional numeric arrays of any type.
AfxSortStringArray	Sorts one-dimensional string arrays of any type.

AppendElementToArray

Appends a new element to a dynamic one-dimensional array.

#macro AppendElementToArray(rg, elem)

Parameter	Description
rg	The array.
elem	The element to append.

Remarks

The array and the element to append can be of any type, but they have to be of the same type between them.

If the array has a fixed length, GetLastError will return an E_ACCESSDENIED error.

Usage example

#define XSTRING DWSTRING ' // or STRING, BSTRING, etc.
DIM rg(ANY) AS XSTRING
DIM xStr AS XSTRING = "String - "
FOR i AS LONG = 1 TO 10
   AppendElementToArray(rg, xStr & WSTR(i))
NEXT
' Display the array
FOR i AS LONG = LBOUND(rg) TO UBOUND(rg)
   print rg(i)
NEXT

AppendArrayToArray

Appends a one-dimensional array to another dynamic one-dimensional array.

#macro AppendArrayToArray(rg, rg2)

Parameter	Description
rg	The array.
rg2	The array to append.

Remarks

The array and the array to append can be of any type, but they have to be of the same type between them.

If the array has a fixed length, GetLastError will return an E_ACCESSDENIED error.

Usage examples

#define XSTRING DWSTRING ' // or STRING, BSTRING, etc.
DIM rg(ANY) AS XSTRING
DIM rg2(ANY) AS XSTRING
DIM xStr AS XSTRING = "String - "
' // Fill the array
FOR i AS LONG = 1 TO 10
   AppendElementToArray(rg, xStr & WSTR(i))
NEXT
' Fill the array to append
xStr = "String 2 - "
FOR i AS LONG = 1 TO 5
   AppendElementToArray(rg2, xStr & WSTR(i))
NEXT
' // Append the array to the first array
AppendArrayToArray(rg, rg2)
' // Display the array
FOR i AS LONG = LBOUND(rg) TO UBOUND(rg)
   print rg(i)
NEXT

Can also be used with numbers:

DIM rg(ANY) AS LONG
DIM rg2(ANY) AS LONG
' // Fill the array
DIM nLong AS LONG = 1
FOR i AS LONG = 1 TO 10
   AppendElementToArray(rg, nLong)
   nLong += 1
NEXT
' Fill the array to insert
nLong = 12345
FOR i AS LONG = 1 TO 5
   AppendElementToArray(rg2, nLong)
   nLong += 1
NEXT
AppendArrayToArray(rg, rg2)
' // Display the array
FOR i AS LONG = LBOUND(rg) TO UBOUND(rg)
   print rg(i)
NEXT

InsertElementIntoArray

Inserts a new element before the specified position into a dynamic one-dimensional array.

#macro InsertElementIntoArray(rg, pos, elem)

Parameter	Description
rg	The array.
pos	The position in the array where the new element will be added. This position is relative to the lower bound of the array.
elem	The element to insert.

Remarks

The array and the array to append can be of any type, but they have to be of the same type between them.

If the array has a fixed length, GetLastError will return an E_ACCESSDENIED error.

Usage examples

#define XSTRING DWSTRING ' // or STRING, BSTRING, etc.
DIM rg(ANY) AS XSTRING
DIM xStr AS XSTRING = "String - "
' // Fill the array
FOR i AS LONG = 1 TO 10
   AppendElementToArray(rg, xStr & WSTR(i))
NEXT
InsertElementIntoArray(rg, 5, xStr & WSTR(11))
' // Display the array
FOR i AS LONG = LBOUND(rg) TO UBOUND(rg)
   print rg(i)
NEXT

Can also be used with numbers:

DIM rg(ANY) AS LONG
DIM rg2(ANY) AS LONG
' // Fill the array
DIM nLong AS LONG = 1
FOR i AS LONG = 1 TO 10
   AppendElementToArray(rg, nLong)
   nLong += 1
NEXT
' Fill the array to insert
nLong = 12345
FOR i AS LONG = 1 TO 5
   AppendElementToArray(rg2, nLong)
   nLong += 1
NEXT
InsertElementIntoArray(rg, 5, nLong)
' // Display the array
FOR i AS LONG = LBOUND(rg) TO UBOUND(rg)
   print rg(i)
NEXT

InsertArrayIntoArray

Inserts a one-dimensional array before the specified position in another dynamic one-dimensional array.

#macro InsertArrayIntoArray(rg, pos, rg2)

Parameter	Description
rg	The array.
pos	The position in the array where the new element will be added. This position is relative to the lower bound of the array.
rg2	The array to insert.

Remarks

The array and the array to insert can be of any type, but they have to be of the same type between them.

If the array has a fixed length, GetLastError will return an E_ACCESSDENIED error.

Usage examples

#define XSTRING DWSTRING ' // or STRING, BSTRING, etc.
DIM rg(ANY) AS XSTRING
DIM rg2(ANY) AS XSTRING
DIM xStr AS XSTRING = "String - "
' // Fill the array
FOR i AS LONG = 1 TO 10
   AppendElementToArray(rg, xStr & WSTR(i))
NEXT
' Fill the array to insert
xStr = "String 2 - "
FOR i AS LONG = 1 TO 5
   AppendElementToArray(rg2, xStr & WSTR(i))
NEXT
' // Insert the array to the first array
InsertArrayIntoArray(rg, 5, rg2)
' // Display the array
FOR i AS LONG = LBOUND(rg) TO UBOUND(rg)
   print rg(i)
NEXT

Can also be used with numbers:

DIM rg(ANY) AS LONG
DIM rg2(ANY) AS LONG
' // Fill the array
DIM nLong AS LONG = 1
FOR i AS LONG = 1 TO 10
   AppendElementToArray(rg, nLong)
   nLong += 1
NEXT
' Fill the array to insert
nLong = 12345
FOR i AS LONG = 1 TO 5
   AppendElementToArray(rg2, nLong)
   nLong += 1
NEXT
' // Insert the array to the first array
InsertArrayIntoArray(rg, 5, rg2)
' // Display the array
FOR i AS LONG = LBOUND(rg) TO UBOUND(rg)
   print rg(i)
NEXT

RemoveElementFromArray

Removes the specified element of a dynamic one-dimensional array.

#macro RemoveElementFromArray(rg, pos)

Parameter	Description
rg	The array.
pos	The position in the array of the element to remove. This position is relative to the lower bound of the array.

Remarks

The array can be of any type.

If the array has a fixed length, GetLastError will return an E_ACCESSDENIED error.

Usage examples

#define XSTRING DWSTRING ' // or STRING, BSTRING, etc.
DIM rg(ANY) AS XSTRING
DIM xStr AS XSTRING = "String - "
' // Fill the array
FOR i AS LONG = 1 TO 10
   AppendElementToArray(rg, xStr & WSTR(i))
NEXT
' // Remove the fifth element
RemoveElementFromArray(rg, 5)
' // Display the array
FOR i AS LONG = LBOUND(rg) TO UBOUND(rg)
   print rg(i)
NEXT

Can also be used with numbers:

DIM rg(ANY) AS LONG
' // Fill the array
DIM nLong AS LONG = 1
FOR i AS LONG = 1 TO 10
   REDIM PRESERVE rg(UBOUND(rg) + 1)
   rg(i - 1) = nLong
   nLong += 1
NEXT
' // Remove the specified element
RemoveElementFromArray(rg, 5)
' // Display the array
FOR i AS LONG = LBOUND(rg) TO UBOUND(rg)
   print rg(i)
NEXT

RemoveFirstElementFromArray

Removes the first element of a dynamic one-dimensional array.

#macro RemoveFirstElementFromArray(rg)

Parameter	Description
rg	The array.

Remarks

The array can be of any type.

If the array has a fixed length, GetLastError will return an E_ACCESSDENIED error.

Usage examples

#define XSTRING DWSTRING ' // or STRING, BSTRING, etc.
DIM rg(ANY) AS XSTRING
DIM xStr AS XSTRING = "String - "
' // Fill the array
FOR i AS LONG = 1 TO 10
   AppendElementToArray(rg, xStr & WSTR(i))
NEXT
' // Remove the frst element
RemoveFirstElementFromArray(rg)
' // Display the array
FOR i AS LONG = LBOUND(rg) TO UBOUND(rg)
   print rg(i)
NEXT

Can also be used with numbers:

DIM rg(ANY) AS LONG
' // Fill the array
DIM nLong AS LONG = 12345
FOR i AS LONG = 1 TO 10
   REDIM PRESERVE rg(UBOUND(rg) + 1)
   rg(i - 1) = nLong
   nLong += 1
NEXT
' // Remove the first element
RemoveFirstElementFromArray(rg)
' // Display the array
FOR i AS LONG = LBOUND(rg) TO UBOUND(rg)
   print rg(i)
NEXT

RemoveLastElementFromArray

Removes the last element of a dynamic one-dimensional array.

#macro RemoveLastElementFromArray(rg)

Parameter	Description
rg	The array.

Remarks

The array can be of any type.

If the array has a fixed length, GetLastError will return an E_ACCESSDENIED error.

Usage examples

#define XSTRING DWSTRING ' // or STRING, BSTRING, etc.
DIM rg(ANY) AS XSTRING
DIM xStr AS XSTRING = "String - "
' // Fill the array
FOR i AS LONG = 1 TO 10
   AppendElementToArray(rg, xStr & WSTR(i))
NEXT
' // Remove the last element
RemoveLastElementFromArray(rg)
' // Display the array
FOR i AS LONG = LBOUND(rg) TO UBOUND(rg)
   print rg(i)
NEXT

Can also be used with numbers:

DIM rg(ANY) AS LONG   ' // or DWORD, SINGLE, DOUBLE, etc.
' // Fill the array
DIM nLong AS LONG = 12345
FOR i AS LONG = 1 TO 10
   REDIM PRESERVE rg(UBOUND(rg) + 1)
   rg(i - 1) = nLong
   nLong += 1
NEXT
' // Remove the last element
RemoveLastElementFromArray(rg)
' // Display the array
FOR i AS LONG = LBOUND(rg) TO UBOUND(rg)
   print rg(i)
NEXT

RemoveElementsFromArray

Removes the specified elements of a dynamic one-dimensional array.

#macro RemoveElementsFromArray(rg, rgElements)

Parameter	Description
rg	The array.
rgElements	Array of long values indicating the 0-based positions of the elements to remove.

Remarks

The array can be of any type.

If the array has a fixed length, GetLastError will return an E_ACCESSDENIED error.

Usage example

DIM rg(ANY) AS LONG
' // Fill the array
DIM nLong AS LONG = 1
FOR i AS LONG = 1 TO 10
   AppendElementToArray(rg, nLong)
   nLong += 1
NEXT
' Fill the array of elements to delete
DIM rgElements(0 TO 3) AS LONG => {2, 4, 6, 8}
RemoveElementsFromArray(rg, rgElements)
' // Display the array
FOR i AS LONG = LBOUND(rg) TO UBOUND(rg)
   print rg(i)
NEXT

AfxSortNumericArray

Sorts one-dimensional numeric array of any type. The macro detects the type of array and calls the appropriate sorting procedures.

#macro AfxSortNumericArray(rg, ascending)

Parameter	Description
rg	The array to sort.
ascending	If true, sorts the array in ascending order. I false, sorts the array in descending order.

Return code

It does not return a result code.

Usage example

#define XNUMBER DOUBLE ' // or SHORT, INTEGER, LONG, LONGINT, etc.
DIM rgNum(ANY) AS XNUMBER
DIM rgNum2(ANY) AS XNUMBER
DIM xNum AS XNUMBER = 1234567.89
' // Fill the array
FOR i AS LONG = 1 TO 10
   xNum += 0.01
   AppendElementToArray(rgNum, xNum)
NEXT
' Fill the array to insert
xNum = 111.01
FOR i AS LONG = 1 TO 5
   xNum += 1
   AppendElementToArray(rgNum, xNum)
NEXT
' // Insert the array to the first array
InsertArrayIntoArray(rgNum, 5, rgNum2)
' // Display the array
FOR i AS LONG = LBOUND(rgNum) TO UBOUND(rgNum)
   print rgNum(i)
NEXT
' // Sort the numeric array
AfxSortNumericArray(rgNum, true)
' // Display the sorted array
FOR i AS LONG = LBOUND(rgNum) TO UBOUND(rgNum)
   print rgNum(i)
NEXT

AfxSortStringArray

Sorts one-dimensional string array of any type. The macro detects the type of array and calls the appropriate sorting procedures.

#macro AfxSortStringArray(rg, ascending)

Parameter	Description
rg	The array to sort.
ascending	If true, sorts the array in ascending order. I false, sorts the array in descending order.

Return code

It does not return a result code.

Usage example

#define XSTRING DWSTRING ' // or STRING, BSTRING, etc.
DIM rgstr(ANY) AS XSTRING
DIM rgstr2(ANY) AS XSTRING
DIM xStr AS XSTRING = "String - "
' // Fill the array
FOR i AS LONG = 1 TO 10
   AppendElementToArray(rgstr, xStr & WSTR(i))
NEXT
' Fill the array to append
xStr = "String 2 - "
FOR i AS LONG = 1 TO 5
   AppendElementToArray(rgstr2, xStr & WSTR(i))
NEXT
' // Append the array to the first array
AppendArrayToArray(rgstr, rgstr2)
' // Display the array
FOR i AS LONG = LBOUND(rgstr) TO UBOUND(rgstr)
   print rgstr(i)
NEXT
' // Sort the array
AfxSortStringArray(rgstr, true)
' // Display the sorted array
FOR i AS LONG = LBOUND(rgstr) TO UBOUND(rgstr)
   print rgstr(i)
NEXT